# MDX 和 React 组件

Rspress 支持 [MDX](https://mdxjs.com/)，这是一种功能强大的内容开发方式。

## Markdown

MDX 是 Markdown 的超集，这意味着你可以像往常一样编写 Markdown 文件。例如：

```md
# Hello world
```

## 组件化

在 MDX 中，所有 `.mdx` 文件都会编译为 React 组件，这意味着它们可以被当做 React 组件使用，也可以自由使用 React 组件。例如：

import { Tabs, Tab } from '@theme';
import { Border } from './_Border';

<Tabs>
<Tab label="docs/index.mdx">

```mdx
import MdxFragment from './_mdx-fragment.mdx';
import TsxComponent from './_tsx-component';

测试 MDX 片段和 React 组件的使用。

<MdxFragment />

<TsxComponent />
```

</Tab>

<Tab label="docs/_mdx-fragment.mdx">

```mdx file="./_mdx-fragment.mdx"

```

</Tab>

<Tab label="docs/_tsx-component.tsx">

```tsx file="./_tsx-component.tsx"

```

</Tab>

</Tabs>

它将被渲染为：

import MdxFragment from './_mdx-fragment.mdx';
import TsxComponent from './_tsx-component';

<Border>
测试 MDX 片段和 React 组件的使用。

<MdxFragment />

<TsxComponent />
</Border>

你可以在 `.mdx` 文件中使用 Rspress 提供的 [内置组件](/guide/default-theme/components) 或安装一些 React 组件库来丰富你的文档。

## 路由约定

在 [docs 目录](/api/config/config-basic#root) 中，使用 MDX 片段或 React 组件要通过 [route.exclude](/api/config/config-basic#routeexclude) 配置从路由中排除。为了使用方便，我们约定以 "\_" 开头的文件会被默认排除，通过 [route.excludeConvention](/api/config/config-basic#routeexcludeconvention)。

你也可以将组件放到 docs 目录以外的相邻目录，例如：

<Tabs>
<Tab label="docsite/docs/index.mdx">

```mdx
import ButtonFragment from './_button.mdx';
import Button from '../../components/button';

<ButtonFragment />
<Button />
```

</Tab>
<Tab label="docsite/docs/_button.mdx">

```mdx file="./_button.mdx"

```

</Tab>
<Tab label="docsite/components/button.tsx">

```tsx
const Button = () => <button>按钮</button>;
export default Button;
```

</Tab>
</Tabs>

它将被渲染为：

<Border>

import Button from './_button.mdx';

<Button />
<button>按钮</button>

</Border>

## 逃生舱：使用 tsx 或 html 编写文档内容

```tsx file="./_escape-hatch.tsx" title="_escape-hatch.tsx"

```

import EscapeHatch from './_escape-hatch';

它将被渲染为：

<Border>
  <EscapeHatch />
</Border>

:::warning

tsx 和 html 语法会导致静态信息难以提取，比如本地搜索索引。

更推荐使用 `.mdx` 文件来编写文档内容，使用 `.tsx` 文件来编写需交互的动态内容。

:::
